feat(releasing): add deprecation.d fragment system by thomasqueirozb · Pull Request #25442 · vectordotdev/vector

thomasqueirozb · 2026-05-15T13:37:21Z

Summary

Introduces a deprecation.d/ fragment system that tracks deprecations as structured markdown files with YAML frontmatter, replacing the hand-maintained docs/DEPRECATIONS.md table.

Each fragment carries:

what — short description of what's deprecated
deprecated_since — concrete semver (e.g. 0.56.0)
optional description — free-form Markdown migration guidance

New `vdev` commands

cargo vdev deprecation show [--version X.Y.Z] — list fragments grouped into announced / planned / enacted buckets for a target release
cargo vdev deprecation enact <slug> [--version X.Y.Z] — record an enacted entry in the generated JSON and remove the fragment
cargo vdev deprecation generate — regenerate website/cue/reference/generated/deprecations.json from fragments
cargo vdev check deprecations — validate fragments and ensure the generated JSON is up to date

CI

A new GitHub Actions workflow (.github/workflows/deprecation.yaml) runs vdev check deprecations when deprecation.d/ or the generated JSON change.

Website

CUE schema additions (#DeprecationEntry, #EnactedDeprecationEntry) and Hugo templates render deprecations on:

individual release pages — announced / planned / enacted partitions
/releases/deprecations index page
a {{< deprecations >}} shortcode for ad-hoc inclusion

The website build pipeline runs vdev deprecation generate before cue-build.

Migration

All 5 entries from docs/DEPRECATIONS.md migrated to fragment files
docs/DEPRECATIONS.md deleted
docs/DEPRECATION.md renamed to docs/DEPRECATION_POLICY.md (links updated in CONTRIBUTING.md, docs/REVIEWING.md)
Minor-release issue template updated to call the new vdev deprecation show / enact steps

Vector configuration

NA

How did you test this PR?

cargo test -p vdev — 59 tests pass
cargo clippy -p vdev — clean
cargo vdev check deprecations — validates all 5 migrated fragments and confirms generated JSON is up to date
cargo vdev deprecation show — verified bucket output
Hugo render: deprecation sections appear correctly on a local release page render

Change Type

Is this a breaking change?

Yes
No

Does this PR include user facing changes?

Yes. Please add a changelog fragment based on our guidelines.
No. A maintainer will apply the no-changelog label to this PR.

References

Related: fix(vdev): release tooling fixes from #25442 #25629 (release tooling fixes previously extracted from this branch)

github-actions · 2026-05-15T13:37:50Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:03:08Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:16:21Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:27:36Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:30:18Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:36:37Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T15:11:58Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T17:31:17Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T17:31:23Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T17:31:31Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

github-actions · 2026-05-15T17:37:25Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T17:37:30Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T17:37:31Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

github-actions · 2026-05-15T18:05:42Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T18:05:47Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T18:05:48Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bc71ccdd4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

The deprecations index lived at /releases/deprecations/ because the content file was under content/en/releases/. That coupled the URL to the releases section even though the page is its own concept (an always-current catalog of active and past deprecations, not a release artifact). Move: content/en/releases/deprecations.md -> content/en/deprecations.md layouts/releases/deprecations.html -> layouts/_default/deprecations.html New URL: /deprecations/. Updated the intra-link in the per-release deprecations partial to point at the new path.

github-actions · 2026-06-17T19:34:23Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-06-17T19:34:32Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-06-17T19:34:33Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

…t flow The "Deprecation" and "Removal" sections still promised that we notify users via the release upgrade guide, but the rewritten Process section treats the deprecation.d fragment (rendered on the release page and the deprecations index) as the canonical user-facing notification. Update both lifecycle sections to match: the fragment / enacted entry is the default; the upgrade guide remains an option for richer treatment when warranted, not a per-deprecation requirement.

github-actions · 2026-06-17T19:37:28Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-06-17T19:37:33Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

github-actions · 2026-06-17T19:37:38Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

…line per review

github-actions · 2026-06-17T21:16:30Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-06-17T21:16:35Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

github-actions · 2026-06-17T21:16:37Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

Apply Thomas's suggestion: the component-docs step now mentions both the cue file path (`deprecation: "..."`) and the macro path (`#[configurable(deprecated = "use <alternative> instead")]`), and notes that the step is conditional ("if applicable") since not every deprecation touches a documented config field.

Enacting a deprecation is part of the PR that removes the deprecated feature, not part of release preparation. By the time the release template kicks in, all enacts should already be on master. Keep the `vdev deprecation show` review checkpoint; drop the `enact` step.

Sharpens the changelog-fragment story: - Announcing a deprecation is communication, not a code change. The feature still works. The deprecation.d/ fragment itself is the announcement; doubling it as a changelog.d/ entry is redundant. Drops the "Add a deprecation changelog fragment" line from the introducing-a-deprecation step. - Enacting (removing) a deprecation IS the breaking change. The feature stops working. That belongs in changelog.d/*.breaking.md alongside other breaking changes. The Past Deprecations section is the lifecycle view for a different reader, not a replacement. Net effect: the two lifecycle stages get the artifacts they actually warrant, with no double-write at either end.

…nges Closes a gap: nothing in the policy required a breaking change to have a prior deprecation announcement, so a PR could ship a removal without warning. Now reviewers should ask for the announcement first, then come back for the removal once the migration window has passed. Restates the existing security/critical-bug exception so it has to be called out deliberately, not by accident.

Per review: - Require `description` (currently optional in the schema; all data has it anyway). - DRY the enacted entry by embedding #DeprecationEntry instead of restating its fields, then adding `removed_in`. Using `&` (or `|`) doesn't work here because #DeprecationEntry is a closed definition; embedding produces the intended four-field shape.

Each release-page deprecation section should exist only for information that isn't already in the changelog. Enactments are recorded as a type="breaking" changelog fragment, so they appear in the per-release Vector Changelog → Breaking changes section. Duplicating them as an "Enacted Deprecations" block on the same page was visible double-write without an additional reader benefit. Announcements are different: they have no changelog fragment (an announcement is not a change), so they only have one release-bound surface and that surface needs to stay. The lifecycle view (active + past deprecations) is preserved on /deprecations/. Only the per-release page is affected here.

github-actions · 2026-06-18T16:25:10Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-06-18T16:25:15Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-06-18T16:25:16Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

thomasqueirozb added the no-changelog Changes in this PR do not need user-facing explanations in the release changelog label May 15, 2026

github-actions Bot added domain: ci Anything related to Vector's CI environment domain: vdev Anything related to the vdev tooling docs review on hold The documentation team reviews PRs only after a PR is approved by the COSE team. labels May 15, 2026

github-actions Bot added the domain: external docs Anything related to Vector's external, public documentation label May 15, 2026

thomasqueirozb force-pushed the website-deprecation-d-releasing branch from d2b0864 to 0bc71cc Compare May 15, 2026 18:05

thomasqueirozb marked this pull request as ready for review May 15, 2026 18:10

thomasqueirozb requested review from a team as code owners May 15, 2026 18:10

thomasqueirozb changed the title ~~feat(releasing): add deprecation.d fragment system with vdev check/show commands and release integration~~ feat(releasing): add deprecation.d fragment system May 15, 2026

chatgpt-codex-connector Bot reviewed May 15, 2026

View reviewed changes

Comment thread deprecation.d/bool-or-vector-compression.md Outdated

Comment thread deprecation.d/example-fake-deprecation.md Outdated

thomasqueirozb mentioned this pull request May 15, 2026

chore(releasing): use gh CLI to fetch VRL release notes instead of unauthenticated GitHub API #25444

Merged

9 tasks

pront reviewed May 19, 2026

View reviewed changes

Comment thread docs/DEPRECATION.md Outdated

github-actions Bot added the docs review on hold The documentation team reviews PRs only after a PR is approved by the COSE team. label Jun 17, 2026

thomasqueirozb commented Jun 17, 2026

View reviewed changes

docs(deprecation policy): tighten the deprecation changelog fragment …

b83712f

…line per review

pront added 6 commits June 17, 2026 17:27

pront added this pull request to the merge queue Jun 19, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jun 19, 2026

thomasqueirozb added this pull request to the merge queue Jun 22, 2026

Merged via the queue into master with commit 127ea00 Jun 22, 2026
172 checks passed

thomasqueirozb deleted the website-deprecation-d-releasing branch June 22, 2026 15:26

github-actions Bot locked and limited conversation to collaborators Jun 22, 2026

Uh oh!

Conversation

thomasqueirozb commented May 15, 2026 • edited by pront Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New vdev commands

CI

Website

Migration

Vector configuration

How did you test this PR?

Change Type

Is this a breaking change?

Does this PR include user facing changes?

References

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

thomasqueirozb commented May 15, 2026 •

edited by pront

Loading

New `vdev` commands